[−][src]Crate crossterm

Crossterm

Have you ever been disappointed when a terminal library for rust was only written for UNIX systems? Crossterm provides clearing, input handling, styling, cursor movement, and terminal actions for both Windows and UNIX systems.

Crossterm aims to be simple and easy to call in code. Through the simplicity of Crossterm, you do not have to worry about the platform you are working with.

This crate supports all UNIX and Windows terminals down to Windows 7 (not all terminals are tested see Tested Terminals for more info).

Command API

The command API makes the use of crossterm much easier and offers more control over when and how a command such as moving the cursor is executed. The command API offers:

Better Performance.
Complete control over when to flush.
Complete control over where the ANSI escape commands are executed to.
Way easier and nicer API.

There are two ways to use the API command:

Functions can execute commands on types that implement Write. Functions are easier to use and debug. There is a disadvantage, and that is that there is a boilerplate code involved.
Macros are generally seen as more difficult but offer an API with less boilerplate code. If you are not afraid of macros, this is a recommendation.

Before crossterm 10.0 was released, crossterm had some performance issues. It did a flush after each command (cursor movement). A flush is heavy action on the terminal, and if it is done more often the performance will go down quickly.

Linux and Windows 10 systems support ANSI escape codes. Those ANSI escape codes are strings or rather a byte sequence. When we write and flush those to the terminal we can perform some action.

Lazy Execution

Because flush is a heavy system call we can instead write the commands to the stdout without flushing. When can do a flush when we do want to execute the commands.

If you create a terminal editor or TUI, it is wise to use this option. For example, you can write commands to the terminal stdout and flush the stdout at every frame. By doing this you can make efficient use of the terminal buffer and get better performance because you are not calling flush after every command.

Examples

Functions:

use std::io::Write;
use crossterm::{Goto, QueueableCommand};

let mut stdout = std::io::stdout();
stdout.queue(Goto(5,5));

// some other code ...

stdout.flush();

The queue function returns itself, therefore you can use this to queue another command. Like stdout.queue(Goto(5,5)).queue(Clear(ClearType::All)).

Macros:

use std::io::Write;
use crossterm::{queue, Goto, QueueableCommand};

let mut stdout = std::io::stdout();
queue!(stdout,  Goto(5, 5));

// some other code ...

stdout.flush();

You can pass more than one command into the macro like queue!(stdout, Goto(5, 5), Clear(ClearType::All)) and they will be executed in the given order from left to right.

Direct Execution

If you want to execute commands directly, this is also possible. You don't have to flush the 'stdout', as described above. This is fine if you are not executing lots of commands.

Examples

Functions:

use std::io::Write;
use crossterm::{ExecutableCommand, Goto};

let mut stdout = std::io::stdout();
stdout.execute(Goto(5,5));

Macros:

use std::io::Write;
use crossterm::{execute, ExecutableCommand, Goto};

let mut stdout = std::io::stdout();
execute!(stdout, Goto(5, 5));

Examples

Print a rectangle colored with magenta and use both direct execution and lazy execution.

Functions:

use std::io::{stdout, Write};
use crossterm::{ExecutableCommand, QueueableCommand, Color, PrintStyledFont, Colorize, Clear, ClearType, Goto, Result};

fn main() -> Result<()> {
  let mut stdout = stdout();

  stdout.execute(Clear(ClearType::All))?;

  for y in 0..40 {
    for x in 0..150 {
      if (y == 0 || y == 40 - 1) || (x == 0 || x == 150 - 1) {
        stdout
          .queue(Goto(x,y))?
          .queue(PrintStyledFont( "█".magenta()))?;
      }
    }
  }
  stdout.flush()?;
  Ok(())
}

Macros:

use std::io::{stdout, Write};
use crossterm::{execute, queue, Color, PrintStyledFont, Colorize, Goto, Clear, ClearType, Result};

fn main() -> Result<()> {
  let mut stdout = stdout();

  execute!(stdout, Clear(ClearType::All))?;

  for y in 0..40 {
    for x in 0..150 {
      if (y == 0 || y == 40 - 1) || (x == 0 || x == 150 - 1) {
        queue!(stdout, Goto(x,y), PrintStyledFont( "█".magenta()))?;
      }
    }
  }
  stdout.flush()?;
  Ok(())
}

Re-exports

pub use cursor::cursor;

pub use cursor::BlinkOff;

pub use cursor::BlinkOn;

pub use cursor::Down;

pub use cursor::Goto;

pub use cursor::Hide;

pub use cursor::Left;

pub use cursor::ResetPos;

pub use cursor::Right;

pub use cursor::SavePos;

pub use cursor::Show;

pub use cursor::TerminalCursor;

pub use cursor::Up;

pub use input::input;

pub use input::InputEvent;

pub use input::KeyEvent;

pub use input::MouseButton;

pub use input::MouseEvent;

pub use input::TerminalInput;

pub use screen::AlternateScreen;

pub use screen::EnterAlternateScreen;

pub use screen::LeaveAlternateScreen;

pub use style::color;

pub use style::style;

pub use style::PrintStyledFont;

pub use style::ResetColor;

pub use style::SetAttr;

pub use style::SetBg;

pub use style::SetFg;

pub use style::TerminalColor;

pub use terminal::terminal;

pub use terminal::Clear;

pub use terminal::ClearType;

pub use terminal::ScrollDown;

pub use terminal::ScrollUp;

pub use terminal::SetSize;

pub use terminal::Terminal;

Modules

cursor	A functionality to work with the terminal cursor
input	A functionality to read the input events.
screen	A functionality to work with the terminal screen.
style	A functionality to apply attributes and colors on your text.
terminal	A functionality to work with the terminal.
utils	Shared utilities.

Macros

csi	Append a the first few characters of an ANSI escape code to the given string.
execute	Execute one or more command(s)
impl_display
impl_from
queue	Queue one or more command(s) for execution in the near future.
write_cout	Write a string to standard output whereafter the stdout will be flushed.

Structs

AsyncReader	An asynchronous input reader (not blocking).
Crossterm	A crossterm functionality wrapper.
ObjectStyle	An object style.
Output	When executed, this command will output the given string to the terminal.
RawScreen	A raw screen.
StyledObject	A styled object.
SyncReader	A synchronous input reader (blocking).

Enums

Attribute	Represents an attribute.
Color	Represents a color.
Colored	Represents a foreground or a background color.
ErrorKind	Wrapper for all errors that can occur in `crossterm`.

Traits

Colorize	Provides a set of methods to set the colors.
Command	A command is an action that can be performed on the terminal.
ExecutableCommand	A trait that defines behaviour for a command that will be executed immediately.
IntoRawMode	Allows to enable raw mode.
QueueableCommand	A trait that defines behaviour for a command that can be used to be executed at a later time point. This can be used in order to get more performance.
Styler	Provides a set of methods to set the text attributes.

Type Definitions

Result

The crossterm result type.